<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
<html>
<head>
<title>Text Element (Eclipse BIRT ROM Documentation)</title>
<link rel="stylesheet" href="../style/style.css" type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body>
<p class="title">Eclipse BIRT Report Object Model (ROM)</p>
<p class="subtitle">Text Element</p>
<h1>Element Overview</h1>
<div class="section-text">
Displays a multi-line block of text defined within the 
report. Can contain embedded formatting and value expressions.</div>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Display Name:</td>
<td>Text</td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>XML Element:</td>
<td><code>text</code></td></tr>
<tr><td>Extends:</td>
<td><a href="ReportItem.html">ReportItem</a></td></tr>
<tr><td>Extendable:</td>
<td>Yes</td></tr>
<tr><td>Abstract:</td>
<td>No</td></tr>
<tr><td>Name Space:</td>
<td>Report Items</td></tr>
<tr><td>Name Requirement:</td>
<td>Optional</td></tr>
<tr><td>Allows User Properties:</td>
<td>Yes</td></tr>
<tr><td>Has Style:</td>
<td>Yes</td></tr>
<tr><td>Default Style:</td>
<td><a href="../styles.html#text">text</a></td></tr>
</table>

<h3>Property Summary</h3>

<dl class="section-text">
<dt><a href="#Property-content">content</a></dt>
<dd>The text for the item.</dd>
<dt><a href="#Property-contentID">contentID</a></dt>
<dd>Resource key for the content.</dd>
<dt><a href="#Property-contentType">contentType</a></dt>
<dd>The formatting within the text: HTML or plain text.</dd>
<dt><a href="#Property-hasExpression">hasExpression</a></dt>
<dd></dd>
</dl>

<h3>Method Summary</h3>

<dl class="section-text">
<dt><a href="#Method-onCreate">onCreate</a></dt>
<dd>Script executed when the element is created in the Factory.</dd>
<dt><a href="#Method-onPageBreak">onPageBreak</a></dt>
<dd></dd>
<dt><a href="#Method-onPrepare">onPrepare</a></dt>
<dd>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</dd>
<dt><a href="#Method-onRender">onRender</a></dt>
<dd>Script executed when the element is prepared for rendering in the Presentation engine.</dd>
</dl>

<h3>Inherited Properties</h3>

<p class="section-text">
<a href="ReportItem.html#Property-ACLExpression">ACLExpression</a>, 
<a href="ReportItem.html#Property-allowExport">allowExport</a>, 
<a href="ReportItem.html#Property-bookmark">bookmark</a>, 
<a href="ReportItem.html#Property-bookmarkDisplayName">bookmarkDisplayName</a>, 
<a href="ReportItem.html#Property-boundDataColumns">boundDataColumns</a>, 
<a href="ReportItem.html#Property-cascadeACL">cascadeACL</a>, 
<a href="ReportElement.html#Property-comments">comments</a>, 
<a href="ReportItem.html#Property-cube">cube</a>, 
<a href="DesignElement.html#Property-customXml">customXml</a>, 
<a href="ReportItem.html#Property-dataBindingRef">dataBindingRef</a>, 
<a href="ReportItem.html#Property-dataSet">dataSet</a>, 
<a href="ReportElement.html#Property-displayName">displayName</a>, 
<a href="ReportElement.html#Property-displayNameID">displayNameID</a>, 
<a href="ReportElement.html#Property-eventHandlerClass">eventHandlerClass</a>, 
<a href="ReportElement.html#Property-extends">extends</a>, 
<a href="ReportItem.html#Property-height">height</a>, 
<a href="ReportItem.html#Property-multiViews">multiViews</a>, 
<a href="ReportElement.html#Property-name">name</a>, 
<a href="ReportElement.html#Property-newHandlerOnEachEvent">newHandlerOnEachEvent</a>, 
<a href="ReportItem.html#Property-paramBindings">paramBindings</a>, 
<a href="DesignElement.html#Property-propertyMasks">propertyMasks</a>, 
<a href="ReportItem.html#Property-pushDown">pushDown</a>, 
<a href="ReportItem.html#Property-refTemplateParameter">refTemplateParameter</a>, 
<a href="ReportItem.html#Property-style">style</a>, 
<a href="ReportItem.html#Property-toc">toc</a>, 
<a href="DesignElement.html#Property-userProperties">userProperties</a>, 
<a href="ReportElement.html#Property-viewAction">viewAction</a>, 
<a href="ReportItem.html#Property-visibility">visibility</a>, 
<a href="ReportItem.html#Property-width">width</a>, 
<a href="ReportItem.html#Property-x">x</a>, 
<a href="ReportItem.html#Property-y">y</a>, 
<a href="ReportItem.html#Property-zIndex">zIndex</a>
</p>
<h3>Style Properties</h3>

<p class="section-text">
<a href="Style.html#Property-backgroundAttachment">backgroundAttachment</a>, 
<a href="Style.html#Property-backgroundColor">backgroundColor</a>, 
<a href="Style.html#Property-backgroundImage">backgroundImage</a>, 
<a href="Style.html#Property-backgroundPositionX">backgroundPositionX</a>, 
<a href="Style.html#Property-backgroundPositionY">backgroundPositionY</a>, 
<a href="Style.html#Property-backgroundRepeat">backgroundRepeat</a>, 
<a href="Style.html#Property-bidiTextDirection">bidiTextDirection</a>, 
<a href="Style.html#Property-borderBottomColor">borderBottomColor</a>, 
<a href="Style.html#Property-borderBottomStyle">borderBottomStyle</a>, 
<a href="Style.html#Property-borderBottomWidth">borderBottomWidth</a>, 
<a href="Style.html#Property-borderLeftColor">borderLeftColor</a>, 
<a href="Style.html#Property-borderLeftStyle">borderLeftStyle</a>, 
<a href="Style.html#Property-borderLeftWidth">borderLeftWidth</a>, 
<a href="Style.html#Property-borderRightColor">borderRightColor</a>, 
<a href="Style.html#Property-borderRightStyle">borderRightStyle</a>, 
<a href="Style.html#Property-borderRightWidth">borderRightWidth</a>, 
<a href="Style.html#Property-borderTopColor">borderTopColor</a>, 
<a href="Style.html#Property-borderTopStyle">borderTopStyle</a>, 
<a href="Style.html#Property-borderTopWidth">borderTopWidth</a>, 
<a href="Style.html#Property-canShrink">canShrink</a>, 
<a href="Style.html#Property-color">color</a>, 
<a href="Style.html#Property-display">display</a>, 
<a href="Style.html#Property-fontFamily">fontFamily</a>, 
<a href="Style.html#Property-fontSize">fontSize</a>, 
<a href="Style.html#Property-fontStyle">fontStyle</a>, 
<a href="Style.html#Property-fontVariant">fontVariant</a>, 
<a href="Style.html#Property-fontWeight">fontWeight</a>, 
<a href="Style.html#Property-highlightRules">highlightRules</a>, 
<a href="Style.html#Property-letterSpacing">letterSpacing</a>, 
<a href="Style.html#Property-lineHeight">lineHeight</a>, 
<a href="Style.html#Property-marginBottom">marginBottom</a>, 
<a href="Style.html#Property-marginLeft">marginLeft</a>, 
<a href="Style.html#Property-marginRight">marginRight</a>, 
<a href="Style.html#Property-marginTop">marginTop</a>, 
<a href="Style.html#Property-masterPage">masterPage</a>, 
<a href="Style.html#Property-orphans">orphans</a>, 
<a href="Style.html#Property-paddingBottom">paddingBottom</a>, 
<a href="Style.html#Property-paddingLeft">paddingLeft</a>, 
<a href="Style.html#Property-paddingRight">paddingRight</a>, 
<a href="Style.html#Property-paddingTop">paddingTop</a>, 
<a href="Style.html#Property-pageBreakAfter">pageBreakAfter</a>, 
<a href="Style.html#Property-pageBreakBefore">pageBreakBefore</a>, 
<a href="Style.html#Property-pageBreakInside">pageBreakInside</a>, 
<a href="Style.html#Property-showIfBlank">showIfBlank</a>, 
<a href="Style.html#Property-textAlign">textAlign</a>, 
<a href="Style.html#Property-textIndent">textIndent</a>, 
<a href="Style.html#Property-textLineThrough">textLineThrough</a>, 
<a href="Style.html#Property-textOverline">textOverline</a>, 
<a href="Style.html#Property-textTransform">textTransform</a>, 
<a href="Style.html#Property-textUnderline">textUnderline</a>, 
<a href="Style.html#Property-verticalAlign">verticalAlign</a>, 
<a href="Style.html#Property-whiteSpace">whiteSpace</a>, 
<a href="Style.html#Property-widows">widows</a>, 
<a href="Style.html#Property-wordSpacing">wordSpacing</a>
</p>
<h3>Description</h3>

<div class="section-text">
<p>The text item allows the developer to provide the text as 
part of the report design. The text can be localized. Text can be in HTML or 
plain text format. HTML text can contain placeholders for data and expressions: 
something line the mail merge feature of a word processing program. &quot;Mail merge&quot; 
is feature in which a standard block of text contains &quot;place holders&quot; for data 
retrieved from a database. It is often used to create form letters, or to format 
specific blocks of text within a report. For example, a report can use the text 
item to display a single line with the US-style city/state/zip address line:</p>

<pre class="code-block">&lt;value-of&gt;row.city&lt;/value-of&gt;,
&lt;value-of&gt;row.state&lt;/value-of&gt;
&lt;value-of&gt;row.zipcode&lt;/value-of&gt;</pre>

<p>Which might appear as:</p>

<pre class="code-block">South San Francisco, CA 94080</pre>

<p>Another example is &quot;mail-merge&quot;, i.e., to incorporate 
personalized data into a block of text. Mail-merge is especially powerful when 
combined with sections to create conditional paragraphs that further customize 
each letter.</p>

<p>The Text item provides many powerful features:</p>

<ul>
<li>Ability to enter formatted text that contains markers for data fields, expressions, and so on. 
When run, the value of each field is concatenated with any static text to produce the final output.</li>

<li>Control text formatting on a character-by-character basis within a single text control. For example, displaying one word in a paragraph in a different font and color from the rest.</li>

<li>Automatically adjust element size based on content.</li>

<li>A single text element can span multiple pages to accommodate large amounts of text.</li>

<li>Specify formatting using embedded HTML.</li>

</ul>

<p>The text object is designed to allow continuous flow of 
text. Creating the same effect with a set of report items (such as labels and 
data items) has the well-known problems that the appearance varies depending on 
characteristics of the printer or display format. (Font widths &amp; heights vary 
across presentation formats, making it difficult to align free-form labels and 
data items.) The user can combine a series of text elements, each in a separate 
section, to create conditional blocks of text.</p>

<p>BIRT leverages HTML and other open standards for 
rendering. For the most part, formatting within a block of text is simply passed 
to the browser or other formatting engine for processing.</p>

<p>A text item can be used to create report headings and 
other textual content. Using a text item is often easier than using a grid, 
free-form or other container. With text, the item contains text instead of 
rectangular report items. Text is placed onto lines. Lines grow and shrink 
depending on the size of their contents just as in Word or HTML. Text can be 
centered, or can be left or right justified. ROM provides control over line 
spacing, paragraph spacing and similar properties.</p>

<p>For example:</p>

<pre class="code-block">&lt;center&gt;&lt;b&gt;&lt;span style=&quot;font-size: larger&quot;&gt;
Monthly Sales Summary&lt;/span&gt;&lt;br&gt;
For the month of:
&lt;value-of&gt;Date.monthName( params.MonthParam )&lt;/value-of&gt;,
&lt;value-of&gt;Date.year( params.MonthParam )&lt;/value-of&gt;
&lt;\b&gt;&lt;/center&gt;</pre>

<p>Displays a report title that looks like this:</p>

<p style="text-align: center"><b>
<span style="font-size: 14.0pt">Monthly Sales Summary</span></b></p>
<p style="text-align: center"><b>For the month of: November, 2004</b></p></div>
<h3>See Also</h3>

<div class="section-text">
<p>Label Item element</p>
<p>Multi-line Data element</p>
<p>Style element, especially the Font and Text properties.</p>
<p>HTML Support section below.</p>
<p>Embedded Expressions section.</p></div>
<h1>Property Detail</h1>

<h2><a name="Property-content">content Property</a></h2>

<p class="section-text">The text for the item.</p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#literalString">literalString</a></td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Content</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>None</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>No</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>The text for the item. See the <code>contentType</code> property for how to identify the text 
formatting. The text can be externalized.</p></div>
<h3>See Also</h3>

<div class="section-text">
<p>&nbsp;</p></div>

<hr>
<h2><a name="Property-contentID">contentID Property</a></h2>

<p class="section-text">Resource key for the content.</p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#resourceKey">resourceKey</a></td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Content key</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>None</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>Yes</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>


<hr>
<h2><a name="Property-contentType">contentType Property</a></h2>

<p class="section-text">The formatting within the text: HTML or plain text.</p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#choice">choice</a> (textContentType)</td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Content type</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>auto</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>No</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>

<h3>Choices</h3>

<table class="section-table">
<thead><tr><td>Name</td><td>Display Name</td>
<td>Value</td><td>Description</td></tr></thead>
<tbody>
<tr><td>auto</td>
<td>Auto</td>
<td>auto</td>
<td>BIRT will infer the 
    format as explained below.</td></tr>
<tr><td>plain</td>
<td>Plain</td>
<td>plain</td>
<td>Plain text with no 
    formatting.</td></tr>
<tr><td>html</td>
<td>HTML</td>
<td>html</td>
<td>Formatting using a 
    subset of HTML tags.</td></tr>
</tbody></table><br>
<h3>Description</h3>

<div class="section-text">
<p>The user can explicitly identify the format of the text 
using the Content Type property. Or, the user can set the property to &quot;auto&quot;, 
(or omit the property) and BIRT will infer the format from the text itself.</p>

<p>BIRT determines the text format by examining the first 
few characters of the string. If the first characters are &quot;&lt;HTML&gt;&quot; (in either 
upper case or lower case), then the string is assumed to be HTML. Otherwise, the 
text is plain text. Any white space before these characters is ignored. That is, 
&quot;&lt;html&gt;&quot; and &quot;&nbsp;&nbsp; &lt;html&gt;&quot; are both taken to indicate that the text is formatted 
in HTML.</p></div>

<hr>
<h2><a name="Property-hasExpression">hasExpression Property</a></h2>

<p class="section-text"></p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#boolean">boolean</a></td></tr>
<tr><td>Since:</td>
<td>2.5</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Has expression</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>true</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>Yes</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>

<h1>Method Detail</h1>

<h2><a name="Method-onCreate">onCreate Method</a></h2>

<p class="section-text">Script executed when the element is created in the Factory.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onCreate(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Context:</td>
<td>factory</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>Executed when the element is created in the Factory. Called after the item is created, but before 
the item is saved to the report document file. See the scripting spec for additional information 
about this script. Applications should perform visual customization in the on-render script instead.</p></div>

<hr>
<h2><a name="Method-onPageBreak">onPageBreak Method</a></h2>

<p class="section-text"></p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onPageBreak(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>2.1</td></tr>
<tr><td>Context:</td>
<td>presentation</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>


<hr>
<h2><a name="Method-onPrepare">onPrepare Method</a></h2>

<p class="section-text">It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onPrepare(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>2.0</td></tr>
<tr><td>Context:</td>
<td>startup</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p></div>

<hr>
<h2><a name="Method-onRender">onRender Method</a></h2>

<p class="section-text">Script executed when the element is prepared for rendering in the Presentation engine.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onRender(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Context:</td>
<td>presentation</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>Executed when the element is prepared for rendering in the Presentation engine. Changes made to the 
element are written to the target output format, but not saved to the report document file. This is the
preferred place for visual customizations.</p></div>
</body>
</html>
